home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audio / alSetParams.z / alSetParams
Encoding:
Text File  |  1998-10-20  |  7.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))                                              aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alSetParams - set the values of audio resource parameters
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  13.  
  14.      iiiinnnntttt aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((iiiinnnntttt rrrreeeessssoooouuuurrrrcccceeee,,,, AAAALLLLppppvvvv ****ppppvvvvssss,,,, iiiinnnntttt nnnnppppvvvvssss))))
  15.  
  16. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  17.      _r_e_s_o_u_r_c_e
  18.             expects the resource on which you wish to set parameter values.
  19.  
  20.      _p_v_s    is an array of ALpv structures, each of which contains a single
  21.             parameter and its desired value.
  22.  
  23.      _n_p_v_s   is the number of ALpv items in the array.
  24.  
  25. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  26.      aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss sets the values for a list of parameters on a specific audio
  27.      resource.
  28.  
  29.      Each parameter/value pair is represented by a single ALpv structure:
  30.  
  31.           typedef struct {
  32.               int     param;          /* parameter */
  33.               ALvalue value;          /* value */
  34.               short   sizeIn;         /* size in -- 1st dimension */
  35.               short   size2In;         /* size out -- 2nd dimension */
  36.               short   sizeOut;        /* size out */
  37.               short   size2Out;        /* size out -- 2nd dimension */
  38.           } ALpv;
  39.  
  40.  
  41.      The application should set the _p_a_r_a_m field in each ALpv to indicate which
  42.      parameter is of interest.
  43.  
  44.      For parameters taking scalar values, the application should fill in the
  45.      appropriate field of the _v_a_l_u_e field. For 32-bit integer values, this is
  46.      the integer field (value.i). For 64-bit integer or fixed-point values,
  47.      this is the long long field (value.ll).
  48.  
  49.      For parameters requiring non-scalar values, the application must set the
  50.      pointer field of _v_a_l_u_e (value.ptr) to point to the structure, and set
  51.      _s_i_z_e_I_n to indicate the size of the structure, in elements.
  52.  
  53.      aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss will set the _s_i_z_e_O_u_t field of each ALpv to indicate how many
  54.      elements of that value it accepted. For valid scalar parameters, this is
  55.      always 1.  For non-scalar parameters, it will set _s_i_z_e_O_u_t to be the
  56.      number of elements accepted. For any parameter, it can also set _s_i_z_e_O_u_t
  57.      to a negative value to indicate an error with that particular
  58.      parameter/value pair. This can be AL_INVALID_PARAM, indicating that the
  59.      given parameter was unrecognized by the given resource, or
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))                                              aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      AL_INVALID_VALUE, indicating that the parameter was recognized but that
  75.      the value was unacceptable.
  76.  
  77.      See the aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) man page for more information on the semantics of
  78.      particular parameters.
  79.  
  80. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  81.      The following example takes the name of a device and a rate in Hz as a
  82.      command-line argument, and sets the rate on that device. Note that the
  83.      device can be an input or output device (however, on a digital input
  84.      device, the rate will be ignored, since such devices get their sample
  85.      rate externally).
  86.  
  87.           #include <audio.h>
  88.           #include <math.h>        /* for atof */
  89.  
  90.           main(int argc, char **argv)
  91.           {
  92.               int rv;
  93.               double rate;
  94.               ALpv x[2];
  95.  
  96.               if (argc != 3) {
  97.                   printf("usage: %s <device> <rate>\n",argv[0]);
  98.                   exit(-1);
  99.               }
  100.  
  101.               /*
  102.                * Get an audio resource of a particular type (AL_DEVICE_TYPE)
  103.                * from the name given on the command line.
  104.                */
  105.               rv = alGetResourceByName(AL_SYSTEM,argv[1],AL_DEVICE_TYPE);
  106.               if (!rv) {
  107.                    printf("invalid device\n");
  108.                    exit(-1);
  109.               }
  110.  
  111.               rate = atof(argv[2]);
  112.  
  113.               /*
  114.                * Attempt to set a crystal-based 48000 Hz sample-rate on the
  115.                * given device.
  116.                */
  117.               x[0].param = AL_MASTER_CLOCK;
  118.               x[0].value.i = AL_CRYSTAL_MCLK_TYPE;
  119.               x[1].param = AL_RATE;
  120.               x[1].value.ll = alDoubleToFixed(rate);
  121.               if (alSetParams(rv,x, 2)<0) {
  122.                    printf("setparams failed: %s\n",alGetErrorString(oserror()));
  123.               }
  124.               if (x[1].sizeOut < 0) {
  125.                printf("rate was invalid\n");
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))                                              aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.               }
  141.           }
  142.  
  143.  
  144. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  145.      aaaallllSSSSeeeettttPPPPaaaarrrraaaammmmssss returns the number of recognized parameters in the given PV
  146.      list. It can also return a negative value, and set an error code, to
  147.      indicate errors with the entire _a_l_S_e_t_P_a_r_a_m_s call. In this case, the error
  148.      code retrieved by oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))) will be one of:
  149.  
  150.      AAAALLLL____BBBBAAAADDDD____PPPPVVVVBBBBUUUUFFFFFFFFEEEERRRR
  151.           _p_v_s is invalid.
  152.  
  153.      AAAALLLL____BBBBAAAADDDD____BBBBUUUUFFFFFFFFEEEERRRRLLLLEEEENNNNGGGGTTTTHHHH
  154.           _n_p_v_s is patently wrong (e.g. negative).
  155.  
  156.      AAAALLLL____BBBBAAAADDDD____DDDDEEEEVVVVIIIICCCCEEEE____AAAACCCCCCCCEEEESSSSSSSS
  157.           The audio system is inaccessible, either because it is not installed
  158.           on the system, or because it is incorrectly configured.
  159.  
  160.      AAAALLLL____BBBBAAAADDDD____RRRREEEESSSSOOOOUUUURRRRCCCCEEEE
  161.           The given resource _r_e_s_o_u_r_c_e does not exist.
  162.  
  163. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  164.      alParams(3dm), alGetParams(3dm), alGetParamInfo(3dm), oserror(3C)
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.